Motion Helper

A C++ example for the maxon Motion Library: connect to an ESCON2 and run a motor in Profile Velocity Mode.

The Motion Helper is two small C++17 classes, MotionDeviceBase and MotionDevicePVM, that wrap the C functions of the maxon Motion Library (VCS2_*) into a device object with a clear sequence: connect, select the operation mode, set the parameters, enable the power stage, command a velocity. The example program in examples/profile_velocity_mode/ shows this sequence end to end and is meant to be copied as the starting point for your own program.

Scope of this version: ESCON2 over USB, Profile Velocity Mode (PVM), Windows, Visual Studio 2022 or 2026. Other operation modes and interfaces are not included; MotionObjects.h explains how to add objects for them.

• Getting Started - installing the Motion Library and Visual Studio, and using the Motion Helper in your own CMake project.
• Examples - building the examples with Visual Studio, Visual Studio Code or the command line.
• Example: Profile Velocity Mode - what the example does, the device state machine in one minute, and what to do when something goes wrong.

Quickstart (run the PVM example)

1. Unpack the ZIP archive from the maxon Support Portal, e.g. to C:\dev\motion_helper\.
2. Open a Developer PowerShell for VS 2022 (or 2026) from the Start menu. It puts cmake, ninja and the compiler cl.exe on the PATH; a plain PowerShell does not work with the presets.
3. Configure, build and run:

cd C:\dev\motion_helper
cmake --preset x64-release
cmake --build build\x64-release
build\x64-release\examples\profile_velocity_mode\example_pvm.exe

Requires an ESCON2 connected over USB, the Motion Library installed (see Getting Started), and motor and sensor parameters already configured with Motion Studio. Motion Studio must be closed while the example runs, because it holds the USB port. The build copies MotionCmd64.dll next to the .exe; the executable does not run without it.

If the configure step ever fails with The CMAKE_C_COMPILER: cl.exe is not a full path, you are not in a Developer PowerShell. Delete the build\ folder before retrying: the failed run leaves a cache behind that later runs would reuse.

Contents of the archive

The same documentation is included as PDF in the archive.

© 2026 maxon. All rights reserved.

Getting Started

Prerequisites

Two things must be installed before the Motion Helper can be built:

• the Motion Library - the communication library from maxon
• Visual Studio 2022 or 2026 - the C++ build tools

Installing the Motion Library

The Motion Library (DLL, import library and header) is only distributed with the Motion Studio installer.

1. Download the Motion Studio installer from the maxon product page, unzip it and start it: https://www.maxongroup.com/en/drives-and-systems/controls/current-and-speed-controllers#software-included-242572

2. Select the package Motion Library for installation.

3. Click "Install" and wait until it has finished.

By default the library is installed to C:\Program Files (x86)\maxon\Motor and Motion Control\Software\Motion Library, and the CMake module finds it there without further configuration.

Installing Visual Studio

Visual Studio 2022 or 2026 with the workload Desktop development with C++. Both are supported; any edition works, including Community.

1. Download Visual Studio: https://visualstudio.microsoft.com/downloads/

2. In the installer, select the workload "Desktop development with C++". It brings the compiler, CMake and Ninja.

3. Wait until it has finished.

Using the Motion Helper in your own project

The Motion Helper is designed for CMake projects. The quickest way to your own program is to copy the example folder examples/profile_velocity_mode/ and edit main.cpp. The steps below describe the same thing for an existing project.

1. Unpack the archive into a folder of your project, e.g. third_party/motion_helper/:

C:\dev\my_motion\
    ├── CMakeLists.txt
    ├── main.cpp
    └── third_party\
        └── motion_helper\
            ├── motion_helper.cmake
            ├── source\
            └── ...

2. In your CMakeLists.txt, include motion_helper.cmake, link the target maxon_MotionHelper and let the module copy the Motion Library DLL next to your executable. A complete minimal file:

cmake_minimum_required(VERSION 3.21)

project(my_motion LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

add_executable(my_motion main.cpp)

# Finds the Motion Library and defines the targets maxon_MotionLibrary and maxon_MotionHelper.
include("${CMAKE_CURRENT_LIST_DIR}/third_party/motion_helper/motion_helper.cmake")

# Linking the helper brings the Motion Library (header and import library) along.
target_link_libraries(my_motion PRIVATE maxon_MotionHelper)

# The Motion Library DLL is not on the PATH; this copies it next to the executable.
maxon_copy_motion_library_dll(my_motion)

The include() may come before or after add_executable(); the two lines that name your target come after it.

3. In main.cpp, include MotionDevicePVM.h and follow the sequence of the example.

Motion Library in a non-default location

If the Motion Library is not installed in its default location, tell CMake where it is - either with a CMake variable before the include():

set(MOTION_LIBRARY_PATH "D:/tools/maxon/Software/Motion Library")
include(".../motion_helper.cmake")

or with an environment variable MOTION_LIBRARY_PATH, or on the command line with -DMOTION_LIBRARY_PATH=.... The path points at the Motion Library folder, not at Windows Motion Library. A path that is set but wrong stops the configure step with an error.

Building from the command line

The CMake presets pin the compiler to cl.exe, so they need a Developer PowerShell for VS (Start menu), not a plain shell. The x86 presets need the x86 Native Tools Command Prompt. See Examples.

Examples

The examples are in the examples folder:

• Profile Velocity Mode - connect to an ESCON2, enable it and control the velocity from the keyboard.

Each example folder is a complete CMake project of its own, and the top-level CMakeLists.txt builds all of them at once. The sections below build the top-level project; the result is the same.

Presets and output location

CMakePresets.json defines four configure presets: x64-debug, x64-release, x86-debug, x86-release. The preset decides the build folder and which Motion Library (64- or 32-bit) is used. The built example is

build\<preset>\examples\profile_velocity_mode\example_pvm.exe

with the Motion Library DLL copied next to it.

Using Visual Studio 2022 or 2026

Visual Studio opens CMake projects directly, without a solution file.

1. Start Visual Studio and choose Open a local folder (or File → Open → Folder...).

2. Select the root folder of the archive - the one that contains CMakeLists.txt and CMakePresets.json. Visual Studio reads the presets and configures the first one; the output window shows the CMake messages.

3. Select the configuration in the presets dropdown of the toolbar, e.g. x64 Release.

4. Build → Build All (Ctrl+Shift+B). The executable is in build\<preset>\... as described above; Debug → Start Without Debugging runs it in a console window.

If Visual Studio reports "Rebuild failed" without any error text after you switched presets or deleted a build folder by hand, the preset has no configured cache yet: run Project → Configure Cache once, then build.

Using Visual Studio Code

1. Install the extension CMake Tools.

2. Start VS Code from a Developer PowerShell for VS (code . in the archive's root folder). The presets pin the compiler to cl.exe, which is only on the PATH in that shell.

3. Press F1 and run - CMake: Select Configure Preset to choose the preset, - CMake: Build to build, - CMake: Run Without Debugging to run.

4. To debug, create .vscode/launch.json with this configuration; it starts the example that CMake Tools has selected as launch target:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Example (external terminal)",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${command:cmake.launchTargetPath}",
      "cwd": "${command:cmake.launchTargetDirectory}",
      "console": "externalTerminal"
    }
  ]
}

Using the command line

The presets need the compiler on the PATH. Open a Developer PowerShell for VS 2022 (or 2026) from the Start menu for the x64 presets, or an x86 Native Tools Command Prompt for VS for the x86 presets, then:

cd C:\dev\motion_helper
cmake --preset x64-release
cmake --build build\x64-release
build\x64-release\examples\profile_velocity_mode\example_pvm.exe

If the configure step fails with The CMAKE_C_COMPILER: cl.exe is not a full path, the shell is not a Developer shell. Delete the build\ folder before retrying; the failed run leaves a cache that later runs would reuse. If it fails with "The compiler on PATH targets 64-bit, but this preset expects 32-bit", the preset and the shell do not match.

Example - Profile Velocity Mode

Prerequisites

• An ESCON2 connected over USB, with logic and motor supply switched on.
• Motor and sensor configured and the controller tuned with Motion Studio, and Motion Studio closed afterwards - it holds the USB port.
• The Motion Library installed and the example built, see Getting Started and Examples.

What the example does

main.cpp follows the Profile Velocity Mode sequence of the ESCON2 Application Notes (table Device programming - Profile Velocity Mode, downloads on the product page):

The console shows the averaged actual velocity, the target velocity and whether a quick stop is active:

Parameters used by the example

Lower MAX_VELOCITY in main.cpp for your first runs.

The device state machine in one minute

The ESCON2 follows the CiA 402 device state machine. Only in Operation Enabled does it accept a target velocity; everything else in the example exists to get there and back. The states the example passes through, and the controlword commands between them:

Switch On Disabled ──«Shutdown»──► Ready To Switch On ──«Enable operation»──► Operation Enabled
        ▲                                                                       │        ▲
        │                                                          «Quick stop» │        │ «Enable operation»
        │                                                                       ▼        │
        │                                                                     Quick Stop Active
        │
        ├── «Disable voltage» ── from every state above: power stage off, shaft coasts
        │
        └── «Fault reset» ────── Fault  (entered from any state when the device detects an error)

Every method that changes the state waits until the device reports the new state and throws if it does not - the message names the state that was expected and the one the device is in. The device enters Fault on its own when it detects an error (supply, overcurrent, sensor, ...); the example checks for it in every loop pass and stops.

When something goes wrong

Error messages from the Motion Library carry the abort code and its description. The codes are listed in Motion Library Specification.pdf in the Manuals folder of the Motion Library installation.

Adapting the example

• Connection: the four strings passed to Connect() at the top of main(). ConnectUsingGUI() shows the valid values.
• Velocity limit and ramps: MAX_VELOCITY and the four values passed to PVM_SetParameters().
• Other objects: ReadObject()/WriteObject() with the constants in source/MotionObjects.h; declare further objects there.
• Another operation mode: derive a class from MotionDeviceBase like MotionDevicePVM, add the mode to OperationMode and its objects to MotionObjects.h, and register the new .cpp and .h in motion_helper.cmake.